// 文件路径: dbms/service/IDbmsService.java
package com.dbms.service;

import com.dbms.common.QueryResult;
import java.io.IOException;

/**
 * 数据库服务接口。
 * <p>
 * 这个接口定义了数据库核心功能的一组标准操作。
 * 它抽象了数据库操作的执行方式，允许系统在不同的部署模式下工作，
 * 例如：
 * <ul>
 * <li><b>本地模式</b>: 直接在同一个JVM中调用数据库核心逻辑 ({@link LocalDbmsService})。</li>
 * <li><b>远程/客户端模式</b>: 通过网络将操作请求发送到远程服务器 ({@link RemoteDbmsService})。</li>
 * </ul>
 * 这种设计使得UI层或应用层可以与数据库服务解耦。
 */
public interface IDbmsService {

    /**
     * 对数据库执行一条或多条SQL命令。
     *
     * @param sql 要执行的SQL语句字符串。
     * @return 一个 {@link QueryResult} 对象，封装了查询的结果或操作的状态。
     */
    QueryResult processSql(String sql);

    /**
     * 验证用户身份。
     *
     * @param username 用户名。
     * @param password 密码。
     * @return 如果认证成功返回 true，否则返回 false。
     */
    boolean authenticate(String username, String password);

    /**
     * 获取当前成功登录的用户名。
     *
     * @return 当前用户的名称字符串。
     */
    String getCurrentUser();

    /**
     * 检查当前会话是否处于一个显式事务（BEGIN...COMMIT/ROLLBACK）中。
     *
     * @return 如果在事务中返回 true，否则返回 false。
     */
    boolean isInTransaction();

    /**
     * 关闭与数据库核心的连接或释放相关资源。
     * <p>
     * 对于本地模式，这通常会触发数据库核心的关闭流程（如刷写缓存到磁盘）。
     * 对于远程模式，这通常会关闭与服务器之间的网络套接字（socket）。
     *
     * @throws IOException 如果在关闭过程中发生I/O错误。
     */
    void close() throws IOException;

    /**
     * 【新增】动态编译并注册一个新的用户自定义函数（UDF）。
     * <p>
     * 允许用户在运行时向数据库添加自定义的Java函数。
     *
     * @param functionName 用户在SQL中调用该函数时使用的名称 (e.g., "REVERSE")。
     * @param sourceCode   该函数的完整Java源代码字符串。
     * @return 一个表示操作结果的消息。如果成功，返回成功消息；如果失败，返回错误详情。
     */
    String registerUdf(String functionName, String sourceCode);
}